تبدیل تقویم با Temporal در جاوا اسکریپت: تسلط بر نگاشت تاریخ بین تقویم‌های مختلف

دنیا تنها بر اساس تقویم میلادی کار نمی‌کند. کسب‌وکارهایی که در سطح جهانی گسترش می‌یابند، باید مناسبت‌های فرهنگی و مذهبی متنوعی را در نظر بگیرند که هر کدام به سیستم‌های تقویمی خاصی مرتبط هستند. API مدرن Temporal در جاوا اسکریپت ابزارهای قدرتمندی برای مدیریت این پیچیدگی‌ها فراهم می‌کند و به توسعه‌دهندگان اجازه می‌دهد تا به طور یکپارچه تاریخ‌ها را بین تقویم‌ها نگاشت کرده و از دقت در زمان‌بندی، محاسبات و نمایش داده‌ها اطمینان حاصل کنند. این راهنمای جامع، قابلیت‌های تبدیل تقویم Temporal API را بررسی می‌کند و مثال‌های عملی و بهترین شیوه‌ها را برای ساخت اپلیکیشن‌های آگاه از فرهنگ جهانی ارائه می‌دهد.

درک نیاز به نگاشت تاریخ بین تقویم‌ها

اشیاء `Date` سنتی جاوا اسکریپت در مدیریت تقویم‌های غیرمیلادی محدودیت‌هایی دارند. Temporal API با ارائه روشی استاندارد و قوی برای کار با سیستم‌های تقویمی مختلف، این مشکل را برطرف می‌کند. این سناریوها را در نظر بگیرید:

• زمان‌بندی جلسات بین‌المللی: تعیین دقیق تاریخ معادل در تقویم اسلامی (هجری) یا عبری برای رویدادی که در تقویم میلادی برنامه‌ریزی شده، برای احترام به تعطیلات مذهبی و حساسیت‌های فرهنگی بسیار مهم است.
• محاسبه سود وام در مناطق مختلف: برخی از مؤسسات مالی از تقویم‌های خاصی برای محاسبات سود استفاده می‌کنند. Temporal امکان محاسبات دقیق تاریخ را در این سیستم‌ها فراهم می‌کند.
• نمایش تاریخ‌ها در قالب‌های دلخواه کاربر: سفارشی‌سازی نمایش تاریخ بر اساس منطقه و تقویم دلخواه کاربر، تجربه کاربری را بهبود می‌بخشد، به‌ویژه برای اپلیکیشن‌هایی که جمعیت‌های متنوعی را هدف قرار داده‌اند.
• تحلیل داده‌های تاریخی: هنگام کار با مجموعه داده‌های تاریخی، درک و تبدیل تاریخ‌های ثبت‌شده در تقویم‌های قدیمی‌تر یا کمتر رایج، برای تفسیر دقیق ضروری می‌شود.

معرفی Temporal API و تقویم‌ها

Temporal API که اکنون در محیط‌های مدرن جاوا اسکریپت به طور گسترده پشتیبانی می‌شود، روشی بصری‌تر و قدرتمندتر برای کار با تاریخ‌ها، زمان‌ها و مناطق زمانی ارائه می‌دهد. در هسته آن، شیء `Temporal.Calendar` یک سیستم تقویمی خاص را نشان می‌دهد. Temporal.PlainDate، Temporal.PlainDateTime و سایر انواع Temporal می‌توانند با یک نمونه `Temporal.Calendar` مرتبط شوند.

Temporal API در حال حاضر (در زمان نگارش این مطلب) از تقویم‌های زیر پشتیبانی می‌کند:

• `iso8601` (میلادی - پیش‌فرض)
• `gregory` (نام مستعار برای `iso8601`)
• `islamic`
• `islamic-umalqura`
• `islamic-tbla`
• `islamic-rgsa`
• `islamic-civil`
• `hebrew`
• `buddhist`
• `roc` (جمهوری چین)
• `japanese`
• `persian`

نسخه‌های آینده ممکن است تقویم‌های بیشتری را معرفی کنند یا امکان پیاده‌سازی تقویم‌های سفارشی را فراهم آورند.

تبدیل تقویم پایه با Temporal.PlainDate

شیء `Temporal.PlainDate` یک تاریخ بدون منطقه زمانی را نشان می‌دهد. شما می‌توانید یک `Temporal.PlainDate` مرتبط با یک تقویم خاص ایجاد کنید:

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');
const islamicDate = Temporal.PlainDate.from({ year: 1445, month: 6, day: 8, calendar: islamicCalendar });

console.log(gregorianDate.toString()); // خروجی: 2024-01-20
console.log(islamicDate.toString());   // خروجی: 1445-06-08[u-ca=islamic]

متد `toString()` تاریخ را با یک حاشیه‌نویسی تقویم `[u-ca=islamic]` خروجی می‌دهد. این نشان می‌دهد که تاریخ با تقویم اسلامی مرتبط است.

تبدیل بین تقویم‌ها

کلید تبدیل بین تقویم‌ها، ایجاد اشیاء `Temporal.PlainDate` مرتبط با هر تقویم و سپس استخراج اجزای تاریخ مربوطه است. در اینجا نحوه تبدیل یک تاریخ میلادی به معادل آن در تقویم اسلامی آورده شده است:

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');

// استخراج اجزای تاریخ در تقویم اسلامی
const islamicYear = gregorianDate.toPlainDate(islamicCalendar).year;
const islamicMonth = gregorianDate.toPlainDate(islamicCalendar).month;
const islamicDay = gregorianDate.toPlainDate(islamicCalendar).day;

console.log(`میلادی: ${gregorianDate.toString()}`);
console.log(`اسلامی: ${islamicYear}-${islamicMonth}-${islamicDay}`); // خروجی: اسلامی: 1445-6-8

بیایید این مثال را تجزیه کنیم:

1. ما با یک `gregorianDate` که به عنوان یک شیء `Temporal.PlainDate` نمایش داده شده است، شروع می‌کنیم.
2. ما یک شیء `islamicCalendar` را با استفاده از `Temporal.Calendar.from('islamic')` ایجاد می‌کنیم.
3. تبدیل اصلی با `gregorianDate.toPlainDate(islamicCalendar)` اتفاق می‌افتد. این یک شیء `Temporal.PlainDate` جدید ایجاد می‌کند که همان نقطه در زمان را نشان می‌دهد، اما اکنون با تقویم اسلامی مرتبط است.
4. ما اجزای `year`، `month` و `day` را از شیء `Temporal.PlainDate` تبدیل‌شده استخراج می‌کنیم.

شما می‌توانید این الگو را برای تبدیل بین هر دو تقویم پشتیبانی‌شده توسط Temporal API تطبیق دهید.

مدیریت پیشرفته تقویم: تقویم‌های اسلامی

تقویم اسلامی چندین نوع دارد. Temporal API از این موارد پشتیبانی می‌کند:

• `islamic`: یک تقویم اسلامی عمومی (پیاده‌سازی ممکن است متفاوت باشد).
• `islamic-umalqura`: بر اساس تقویم ام‌القری عربستان سعودی.
• `islamic-tbla`: بر اساس محاسبات جدولی.
• `islamic-rgsa`: بر اساس دبیرخانه کل امور دینی اوقاف (مصر).
• `islamic-civil`: یک نسخه کاملاً حسابی از تقویم اسلامی که عمدتاً برای محاسبات استفاده می‌شود.

هنگام کار با تقویم اسلامی، درک اینکه کدام نوع برای مورد استفاده شما مناسب است، بسیار مهم است. به عنوان مثال، برای مناسبت‌های مذهبی در عربستان سعودی، احتمالاً می‌خواهید از `islamic-umalqura` استفاده کنید. برای محاسبات مالی، `islamic-civil` ممکن است به دلیل ماهیت قابل پیش‌بینی‌اش مناسب‌تر باشد.

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const islamicUmalquraCalendar = Temporal.Calendar.from('islamic-umalqura');
const islamicCivilCalendar = Temporal.Calendar.from('islamic-civil');

const islamicUmalquraDate = gregorianDate.toPlainDate(islamicUmalquraCalendar);
const islamicCivilDate = gregorianDate.toPlainDate(islamicCivilCalendar);

console.log(`میلادی: ${gregorianDate.toString()}`);
console.log(`اسلامی (ام‌القری): ${islamicUmalquraDate.year}-${islamicUmalquraDate.month}-${islamicUmalquraDate.day}`);
console.log(`اسلامی (حسابی): ${islamicCivilDate.year}-${islamicCivilDate.month}-${islamicCivilDate.day}`);

ملاحظات مهم برای تقویم‌های اسلامی:

• شروع یک ماه جدید در تقویم اسلامی بر اساس رؤیت هلال ماه نو است. تقویم `islamic-umalqura` تلاش می‌کند با رؤیت واقعی ماه در عربستان سعودی هماهنگ باشد، اما هنوز هم ممکن است مغایرت‌هایی رخ دهد.
• تقویم `islamic-civil` یک تقریب ریاضی است و رؤیت واقعی ماه را منعکس نمی‌کند.
• همیشه برای تاریخ‌های دقیق تعطیلات اسلامی با مراجع مذهبی مربوطه یا منابع معتبر مشورت کنید.

کار با تقویم عبری

تقویم عبری یک تقویم قمری-خورشیدی است که برای مناسبت‌های مذهبی یهودیان و به عنوان تقویم رسمی در اسرائیل استفاده می‌شود. این تقویم شامل ماه‌های کبیسه برای هماهنگ نگه داشتن آن با فصول است.

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const hebrewCalendar = Temporal.Calendar.from('hebrew');

const hebrewDate = gregorianDate.toPlainDate(hebrewCalendar);

console.log(`میلادی: ${gregorianDate.toString()}`);
console.log(`عبری: ${hebrewDate.year}-${hebrewDate.month}-${hebrewDate.day}`);

ویژگی‌های کلیدی تقویم عبری و Temporal:

• ماه‌های کبیسه به طور خودکار توسط Temporal API مدیریت می‌شوند. نیازی به پیاده‌سازی منطق سفارشی برای تعیین سال‌های کبیسه یا افزودن ماه‌های اضافی ندارید.
• شماره‌گذاری سال از مبدأ سنتی یهودی (خلقت جهان) شروع می‌شود.
• نام‌های ماه‌های تقویم عبری با تقویم میلادی متفاوت است. شما می‌توانید از طریق کتابخانه‌های بین‌المللی‌سازی (i18n) یا نگاشت‌های سفارشی به این نام‌های ماه دسترسی پیدا کنید.

کار با تقویم‌های بودایی، ROC، ژاپنی و فارسی

Temporal API از تقویم‌های دیگری نیز پشتیبانی می‌کند که هر کدام ویژگی‌های خاص خود را دارند. در اینجا چند نکته قابل توجه است:

• تقویم بودایی: تقویم بودایی یک تقویم قمری-خورشیدی است که در بسیاری از کشورهای جنوب شرقی آسیا استفاده می‌شود. شماره‌گذاری سال معمولاً از زمان درگذشت بودا شروع می‌شود.
• تقویم ROC (جمهوری چین): این تقویم در تایوان استفاده می‌شود و سال‌ها را از زمان تأسیس جمهوری چین در سال 1912 شماره‌گذاری می‌کند.
• تقویم ژاپنی: تقویم ژاپنی بر اساس تقویم میلادی است اما از نام‌های دوره‌های ژاپنی (nengō) برای نشان دادن سال‌ها استفاده می‌کند.
• تقویم فارسی: تقویم فارسی یک تقویم خورشیدی است که عمدتاً در ایران و افغانستان استفاده می‌شود.

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const buddhistCalendar = Temporal.Calendar.from('buddhist');
const rocCalendar = Temporal.Calendar.from('roc');
const japaneseCalendar = Temporal.Calendar.from('japanese');
const persianCalendar = Temporal.Calendar.from('persian');

const buddhistDate = gregorianDate.toPlainDate(buddhistCalendar);
const rocDate = gregorianDate.toPlainDate(rocCalendar);
const japaneseDate = gregorianDate.toPlainDate(japaneseCalendar);
const persianDate = gregorianDate.toPlainDate(persianCalendar);

console.log(`میلادی: ${gregorianDate.toString()}`);
console.log(`بودایی: ${buddhistDate.year}-${buddhistDate.month}-${buddhistDate.day}`);
console.log(`ROC: ${rocDate.year}-${rocDate.month}-${rocDate.day}`);
console.log(`ژاپنی: ${japaneseDate.year}-${japaneseDate.month}-${japaneseDate.day}`);
console.log(`فارسی: ${persianDate.year}-${persianDate.month}-${persianDate.day}`);

هنگام استفاده از این تقویم‌ها، از مبدأ (سال شروع) خاص آنها و هرگونه تفاوت‌های ظریف فرهنگی مرتبط با نمایش تاریخ آگاه باشید.

Temporal.Now و ملاحظات تقویم

در حالی که می‌توان از `Temporal.Now` برای دریافت تاریخ و زمان فعلی استفاده کرد، مهم است که بدانید به طور پیش‌فرض تاریخ و زمان فعلی را در تقویم ISO 8601 برمی‌گرداند. اگر به تاریخ فعلی در تقویم دیگری نیاز دارید، باید آن را تبدیل کنید:

const islamicCalendar = Temporal.Calendar.from('islamic');
const now = Temporal.Now.plainDateISO(); // تاریخ فعلی در تقویم ISO 8601
const islamicNow = now.toPlainDate(islamicCalendar);

console.log(`تاریخ میلادی فعلی: ${now.toString()}`);
console.log(`تاریخ اسلامی فعلی: ${islamicNow.year}-${islamicNow.month}-${islamicNow.day}`);

قالب‌بندی تاریخ و بین‌المللی‌سازی (i18n)

تبدیل تاریخ‌ها تنها بخشی از معادله است. شما همچنین باید آنها را برای نمایش به درستی قالب‌بندی کنید. API `Intl.DateTimeFormat` جاوا اسکریپت قابلیت‌های قدرتمند بین‌المللی‌سازی را فراهم می‌کند. شما می‌توانید از آن در ترکیب با Temporal API برای قالب‌بندی تاریخ‌ها به روشی آگاه از منطقه، با در نظر گرفتن تقویم مرتبط، استفاده کنید.

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');
const islamicDate = gregorianDate.toPlainDate(islamicCalendar);

const formatter = new Intl.DateTimeFormat('ar-SA-u-ca-islamic', { // عربی (عربستان سعودی) با تقویم اسلامی
  year: 'numeric',
  month: 'long',
  day: 'numeric',
});

console.log(formatter.format(islamicDate)); // خروجی نمونه: ٢٠ رجب، ١٤٤٥ هـ

بیایید کد را تحلیل کنیم:

• `'ar-SA-u-ca-islamic'` رشته منطقه است. `ar-SA` زبان عربی (عربستان سعودی) را مشخص می‌کند و `u-ca-islamic` به صراحت تقویم اسلامی را درخواست می‌کند.
• گزینه‌های `Intl.DateTimeFormat` نحوه قالب‌بندی تاریخ (سال، ماه، روز) را کنترل می‌کنند.
• متد `format()` یک شیء `Temporal.PlainDate` (در این مورد `islamicDate`) را می‌گیرد و یک رشته قالب‌بندی‌شده را بر اساس منطقه و تقویم مشخص‌شده برمی‌گرداند.

شما می‌توانید رشته منطقه و گزینه‌های قالب‌بندی را متناسب با نیازهای خاص خود تطبیق دهید. به عنوان مثال، برای قالب‌بندی تاریخ به زبان عبری:

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const hebrewCalendar = Temporal.Calendar.from('hebrew');
const hebrewDate = gregorianDate.toPlainDate(hebrewCalendar);

const formatter = new Intl.DateTimeFormat('he-IL-u-ca-hebrew', { // عبری (اسرائیل) با تقویم عبری
  year: 'numeric',
  month: 'long',
  day: 'numeric',
});

console.log(formatter.format(hebrewDate));

نکاتی برای قالب‌بندی مؤثر تاریخ:

• از رشته‌های منطقه‌ای استفاده کنید که زبان و منطقه ترجیحی کاربر را به دقت منعکس کنند.
• گزینه‌های قالب‌بندی را انتخاب کنید که برای زمینه مناسب باشند (مثلاً، قالب‌های تاریخ کوتاه برای نمایش‌های فشرده، قالب‌های تاریخ بلند برای ارائه‌های دقیق).
• قالب‌بندی خود را در مناطق مختلف آزمایش کنید تا از صحت و خوانایی اطمینان حاصل کنید.

انجام محاسبات تاریخ بین تقویم‌ها

Temporal API در محاسبات تاریخ عالی عمل می‌کند. شما می‌توانید روزها، ماه‌ها یا سال‌ها را از یک شیء `Temporal.PlainDate` اضافه یا کم کنید، حتی هنگام کار با تقویم‌های غیرمیلادی.

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');
const islamicDate = gregorianDate.toPlainDate(islamicCalendar);

// اضافه کردن 30 روز به تاریخ اسلامی
const futureIslamicDate = islamicDate.add({ days: 30 });

console.log(`تاریخ اسلامی اصلی: ${islamicDate.year}-${islamicDate.month}-${islamicDate.day}`);
console.log(`تاریخ اسلامی + 30 روز: ${futureIslamicDate.year}-${futureIslamicDate.month}-${futureIslamicDate.day}`);

// تبدیل تاریخ اسلامی آینده به میلادی
const futureGregorianDate = futureIslamicDate.toPlainDate('iso8601');
console.log(`تاریخ میلادی معادل: ${futureGregorianDate.toString()}`);

ملاحظات کلیدی برای محاسبات تاریخ:

• متدهای `add()` و `subtract()` اشیاء `Temporal.PlainDate` جدیدی را برمی‌گردانند؛ آنها شیء اصلی را تغییر نمی‌دهند.
• هنگام اضافه یا کم کردن ماه‌ها یا سال‌ها، Temporal API قوانین خاص تقویم را برای سال‌های کبیسه و طول ماه‌ها مدیریت می‌کند.
• هنگام انجام محاسبات، مراقب سرریز یا زیرریز احتمالی تاریخ باشید. Temporal API معمولاً تاریخ را به نزدیک‌ترین تاریخ معتبر در آن تقویم تنظیم می‌کند.

مدیریت تاریخ‌های مبهم

در برخی موارد، یک تاریخ ممکن است هنگام تبدیل بین تقویم‌ها مبهم باشد. این می‌تواند زمانی رخ دهد که یک تاریخ خاص در تقویم مقصد وجود نداشته باشد یا زمانی که چندین تاریخ در تقویم مقصد می‌توانند با تاریخ مبدأ مطابقت داشته باشند. Temporal این موقعیت‌ها را به آرامی مدیریت می‌کند، معمولاً با برگرداندن نزدیک‌ترین تاریخ معتبر.

به عنوان مثال، تبدیل یک تاریخ میلادی نزدیک به پایان یک ماه میلادی به تقویم اسلامی را در نظر بگیرید، جایی که ماه اسلامی مربوطه ممکن است کوتاه‌تر باشد. Temporal به طور خودکار تاریخ اسلامی حاصل را به آخرین روز آن ماه تنظیم می‌کند.

مدیریت خطا و اعتبارسنجی

در حالی که Temporal API قوی است، پیاده‌سازی مدیریت خطا و اعتبارسنجی مناسب برای جلوگیری از رفتار غیرمنتظره ضروری است. در اینجا چند سناریوی رایج برای در نظر گرفتن وجود دارد:

• نام‌های تقویم نامعتبر: اگر نام تقویم نامعتبر را به `Temporal.Calendar.from()` بدهید، یک `RangeError` پرتاب خواهد کرد. این خطا را بگیرید و یک پیام کاربرپسند ارائه دهید.
• قالب‌های تاریخ نامعتبر: اگر سعی کنید یک `Temporal.PlainDate` از یک رشته تاریخ نامعتبر ایجاد کنید، یک `RangeError` پرتاب خواهد کرد. رشته‌های تاریخ را قبل از ارسال به `Temporal.PlainDate.from()` اعتبارسنجی کنید.
• عملیات پشتیبانی نشده: برخی از عملیات خاص تقویم ممکن است توسط Temporal API پشتیبانی نشوند. مستندات مربوط به تقویم خاصی که استفاده می‌کنید را بررسی کنید.

بهترین شیوه‌ها برای نگاشت تاریخ بین تقویم‌ها

برای اطمینان از دقت و قابلیت نگهداری هنگام کار با نگاشت تاریخ بین تقویم‌ها، این بهترین شیوه‌ها را دنبال کنید:

• از Temporal API استفاده کنید: Temporal API روشی استاندارد و قوی برای مدیریت تبدیل تقویم‌ها فراهم می‌کند. از استفاده از اشیاء `Date` قدیمی جاوا اسکریپت برای این منظور خودداری کنید.
• تقویم‌ها را به صراحت مشخص کنید: همیشه هنگام ایجاد اشیاء `Temporal.PlainDate` تقویم را به صراحت مشخص کنید. این از ابهام جلوگیری می‌کند و اطمینان می‌دهد که قوانین تقویمی صحیح اعمال می‌شوند.
• نوع مناسب تقویم اسلامی را انتخاب کنید: تفاوت‌های بین پیاده‌سازی‌های مختلف تقویم اسلامی را درک کنید و آنی را انتخاب کنید که برای مورد استفاده شما مناسب‌تر است.
• از بین‌المللی‌سازی (i18n) استفاده کنید: از `Intl.DateTimeFormat` API برای قالب‌بندی تاریخ‌ها به روشی آگاه از منطقه استفاده کنید.
• مدیریت خطا را پیاده‌سازی کنید: مدیریت خطای قوی برای گرفتن نام‌های تقویم نامعتبر، قالب‌های تاریخ و سایر مسائل احتمالی پیاده‌سازی کنید.
• به طور کامل آزمایش کنید: کد خود را با انواع تاریخ‌ها و مناطق مختلف آزمایش کنید تا از صحت و سازگاری اطمینان حاصل کنید.
• به‌روز بمانید: Temporal API هنوز در حال تکامل است. با آخرین مشخصات و پیاده‌سازی‌های مرورگرها به‌روز بمانید.

نتیجه‌گیری

Temporal API جاوا اسکریپت نحوه مدیریت تاریخ‌ها و تقویم‌ها را متحول می‌کند و روشی قدرتمند و استاندارد برای انجام نگاشت تاریخ بین تقویم‌ها فراهم می‌کند. با درک تفاوت‌های ظریف سیستم‌های تقویمی مختلف و استفاده مؤثر از Temporal API، توسعه‌دهندگان می‌توانند اپلیکیشن‌های آگاه از فرهنگ جهانی بسازند که نیازهای متنوع فرهنگی و مذهبی را برآورده می‌کنند. از Temporal API برای ایجاد راه‌حل‌های مدیریت تاریخ فراگیرتر و دقیق‌تر در پروژه‌های خود استفاده کنید.

این راهنما یک مرور جامع از تبدیل تقویم با Temporal API جاوا اسکریپت ارائه داد. به یاد داشته باشید که برای به‌روزترین اطلاعات و مشخصات دقیق، به مستندات رسمی Temporal API مراجعه کنید.